Inside Macintosh: Open Transport /

Chapter 16 - Serial Endpoint Providers

Using Serial Endpoints

Serial endpoint providers use standard Open Transport functions for binding, requesting and accepting connections, sending and receiving data, and managing options. You can send and receive the desired data using the standard Open Transport OTSnd and OTRcv functions. You can call these functions either synchronously or asynchronously, as described in the chapter "Endpoints" in this book.

In addition, Open Transport provides specialized serial-specific commands and options that allow you to

• set the flow-control handshaking
• use an external timing signal for synchronous clocking
• set or clear a break signal
• get status information about a port and any associated transmission errors
• define how characters with parity errors are handled
• request burst mode operation
• define receive timeout options
• set the framing type

Opening and Closing Serial Endpoints

To open serial endpoints, you need to supply a configuration string to the OTOpenEndpoint function by using one of the following constants:

Constant name	String value	Description
kSerialName	"serial"	Default serial port
kSerialPortAName	"serialA"	Serial port A
kSerialPortBName	"serialB"	Serial port B
kSerialPortABName	"serialAB"	Serial port AB

For example, the following line of code opens a serial endpoint on serial port A:

OTOpenEndpoint(OTCreateConfiguration(kSerialPortAName));

To close a serial endpoint provider, you use the standard Open Transport function OTCloseProvider, described in the chapter "Providers" in this book.

Sending and Receiving Data

As with all endpoints, you must call the OTBind function before you can use a serial endpoint provider to send or receive data. For serial endpoint providers that initiate outgoing data, you need to bind with a queue length (the qlen parameter) of 0. When you wish to start transferring data, you must call the OTConnect function to place the endpoint in the data transfer state and allow you to call the OTSnd and OTRcv functions. Calling the OTSndDisconnect function releases the connection.

For serial endpoint providers that listen for incoming data, you need to bind with a queue length of 1. You cannot bind with a queue length greater than 1. When an incoming character is detected on the serial port, you receive a connect indication. You can accept the indication on the current endpoint, or you can accept it on another serial endpoint, which has a queue length of 0 or which is not yet bound. In either case, once the accepting endpoint returns to the T_IDLE state, the original endpoint once again listens for incoming data and gets a connect indication if another incoming character is detected. Calling the OTSndDisconnect function releases the connection and allows your endpoint to continue listening on the port. Your endpoint can continue to listen until you call the OTUnbind function.

You can create a number of serial endpoints to listen on a given serial port, but only one can have a connection at a time. The first serial endpoint to connect owns the hardware; other endpoints that subsequently attempt to connect receive a kOTAddressBusyErr result code.

Using Serial-Specific Commands

You can control several aspects of serial communication by using the Open Transport function OTIoctl with different serial-specific commands. The OTIoctl function, described in the chapter "Providers" in this book, accesses the low-level serial driver control and status functions (PBControlAsync or PBStatusAsync). For information about Device Manager functions for opening, closing, and communicating with device drivers, see the book Inside Macintosh: Devices.

You can assert the DTR signal for the serial port by using a value of kOTSerialSetDTROn with the I_SetSerialDTR command and you can negate it with a value of kOTSerialSetDTROff. Likewise, you can use the I_SetSerialBreak command to set or negate the break signal with values of kOTSerialSetBreakOn and kOTSerialSetBreakOff or you can use a number greater than 1 to indicate the number in milliseconds to assert a break signal temporarily.

You can also use the OTIoctl function commands to set the XOFF state of the serial port and to indicate whether the port is to send an XOFF or XON character. Using a value of kOTSerialForceXOffTrue with the I_SetSerialXOffState command sets the XOFF state of the serial port, which is equivalent to receiving an XOFF character, and using a value of kOTSerialForceXOffFalse with this command clears the XOFF state, which is equivalent to receiving an XON character.

Using a value of 1 with the I_SetSerialXOn and I_SetSerialXOff commands causes the serial port to unconditionally send an XON or XOFF character, respectively. A value of 0 with these functions causes the character to be sent only if the last input flow-control character sent was the opposite kind--that is, the XOFF or XON character, respectively.

Using Options to Change Serial Communications Settings

Serial endpoints currently support six options. These options are defined by the XTI-level constant COM_SERIAL, which has a value of 'SERL'.

When you open a serial endpoint, Open Transport configures the selected port with the default settings of 19200 baud, 8 data bits per character, no parity bit, 1 stop bit, and no handshaking. You can change these settings using various options, all of which use 4-byte unsigned integer values. There is also a serial status option that provides current information about the serial port. Four of the options are fairly straightforward and are described here; using the other two options is more complicated, and their use is described in the two subsequent sections.

• The baud rate option sets the serial baud rate.The serial module chooses the closest baud rate supported that matches the requested rate. Possible values range from 300 to 57600 baud transmission rates (depending on the hardware capability). The default value is 19200 baud.
• The data bits option selects the number of data bits to be used. Legal values are 5, 6, 7, and 8. The default value is 8 data bits.
• The stop bits option selects the number of stop bits to be used. This value corresponds to ten (10) times the actual number of stop bits. Legal values are 10, 15, and 20, which correspond to stop bits of 1, 1.5, and 2. The default value is 10, which is equivalent to 1 stop bit.
• The parity option selects the parity to be used. Legal values are kOTNoParity 0), kOTOddParity(1), and kOTEvenParity(2). The default value is kOTNoParity.
• The receive timeout option sets the number of milliseconds the receiver should wait to receive more data before timing out.
• The error character option defines how characters with parity errors are handled--that is, if they are replaced and with which character. Open Transport provides the define statements (and C++ inline functions), OTSerialSetErrorCharacter and OTSerialSetErrorCharacterWithAlternate, to help place the character bits correctly.
• The external clock option requests an external clock. This option may not be supported by all serial drivers.
• The burst mode option requests that the serial driver continues looping, reading incoming characters, rather than waiting for an interrupt for each character. This option may not be supported by all serial drivers.

Setting Flow-Control Handshaking

This option selects the flow-control handshaking to be used by the serial endpoint providers. The handshaking can be either hardware, using the DTR and CTS signals, or software, using the XON and XOFF characters. The default value of this option is no handshaking.

A schematic diagram of this 4-byte option value looks like this:

xxxxxxxxxxxxxxxx  xxxxxxxx       xxxxxxxx
handshake bitmap  XON character  XOFF character

The high word is a bitmap with one or more bits set, indicating the type of handshaking requested. The DTR signal is normally asserted when the serial endpoint is opened and negated when it is closed. The CTS signal is normally always asserted. If the XON and XOFF character values are 0 and if XON/OFF handshaking was requested, Open Transport uses the default values of Control-S for XOFF and Control-Q for XON.

Open Transport provides a define statement and a C++ inline function (SerialHandshakeData) that you can use to create the 4-byte option value.

Obtaining Status Information About the Serial Port

The serial status option is a read-only option that returns status information on the serial port. It is a 4-byte unsigned integer containing a bitmap that can provide the following information about errors or changes in status that may have occured:

• A hardware overrun has occurred due to an overflow of the hardware
  input buffer.
• A software overrun has occurred due to an overflow of the software
  input buffer.
• A parity error has occurred due to the serial hardware detecting an incorrect parity bit.
• A framing error has occurred due to the serial hardware detecting a stop
  bit error.
• A break has occurred on the line, and the break signal has been asserted.
• The endpoint provider has sent an XOFF character, which initiates
  flow control.
• The endpoint provider has negated the DTR signal, which initiates
  flow control.
• The endpoint provider has negated the CTS signal, which initiates
  flow control.
• The endpoint provider has received an XOFF character, and so all output is on hold.
• The endpoint provider has initiated a break that is still in progress.

Data received from the serial port passes through a hardware buffer and then into a software buffer managed by the input driver for the port. Each input driver's buffer can initially hold up to 64 characters, but you can specify a larger buffer with standard Open Transport functions. This is normally not necessary because Open Transport provides additional buffering as part of its processing.

Because the serial hardware in some Macintosh computers relies on processor interrupts during I/O operations, overrun errors are possible if interrupts are disabled while data is being received at the serial port. To prevent such errors, the Disk Driver and other system software components are designed to store any data received by the modem port while they have interrupts disabled and then pass this data to the port's input driver. Because the system software only monitors the modem port, the printer port is not recommended for two-way communication at data rates above 300 baud.

Overrun, parity, and framing errors are usually handled by requesting that the sender retransmit the affected data. Break errors are typically initiated by the client application, which handles them as appropriate.

Using General Open Transport Functions
With Serial Endpoints

This section describes any special considerations that you must take into account for Open Transport functions when you use them with serial endpoint providers. You should be familiar with the function descriptions in the chapter "Endpoints" in this book before reading this section.

Obtaining Endpoint Data With Serial Endpoints

This section describes the possible values you can get for endpoint information when using a serial endpoint.

OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo

The following values can be returned by the info parameter to the OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo functions when used with serial endpoint providers:

Parameter	Serial	Meaning
info->addr	0	Addresses are not used.
info->options	Greater than 0	Maximum number of bytes needed to hold protocol-specific options.
info->tsdu	T_INVALID	TSDUs are not supported.
info->etsdu	T_INVALID	Transfer of expedited data is not supported.
info->connect	T_INVALID	Data cannot be sent with functions that establish connections.
info->discon	T_INVALID	Data cannot be sent with abortive disconnects.
info->servtype	T_COTS	Orderly disconnects are not supported.
info->flags	-	No flags are set.

IMPORTANT

The values shown in the preceding table are subject to change. Be sure to to use the OTOpenEndpoint, OTAsyncOpenEndpoint, or OTGetEndpointInfo function to obtain the current values for these parameters.

These fields and the significance of their values are described in more detail in the document X/Open CAE Specification: X/Open Transport Interface (XTI).

Using Endpoint Functions With Serial Endpoints

This section describes serial-specific information about functions described in the chapter "Endpoints" in this book.

OTBind

The OTBind function associates a serial port with the endpoint you specify. Because serial communication is point-to-point over a hardware connection, you cannot specify an address. Therefore, you must specify 0 as the length of the address in the reqaddr->TBind.addr.len parameter. You can bind multiple serial endpoints to listen at a single port.

With serial endpoints, the req->qlen parameter, which specifies the number of outstanding connection requests that an endpoint can support, can only have a value of 0 or 1. To listen, a serial endpoint provider must have a queue length value of 1; to accept connections, the endpoint can have a value of 0 or 1. A value greater than 1 results in a error code.

OTConnect

The OTConnect function requests a connection to a specified remote endpoint.

Because serial endpoint providers do not allow you to send any application-
specific data during the connection establishment phase, you must set the sndcall->udata.len field to 0. Serial endpoints ignore any data in the sndcall->udata.buf field.

OTListen

The OTListen function listens for an incoming connection request.

Serial endpoints do not allow application-specific data to be included when you request a connection, so you need to set the call->udata.len field to 0. Serial endpoints ignore the call->udata.buf field.

OTAccept

The OTAccept function accepts a connection request. You can accept a connection either on the same endpoint that received the connection request or on a different endpoint.

Serial endpoints do not allow application-specific data to be included when you accept a connection, so you need to set the call->udata.len field to 0. Serial endpoints ignore the call->udata.buf field.

OTSnd

The OTSnd function sends data through a connection-oriented transactionless endpoint. Serial endpoints do not support TSDUs.

OTRcv

The OTRcv function receives data through a connection-oriented transactionless endpoint. Serial endpoints do not support TSDUs.

OTSndDisconnect

The OTSndDisconnect function initiates an abortive disconnect or rejects a connection request.

In an abortive disconnect, the call parameter is ignored because serial endpoints do not allow application-specific data to be associated with a disconnect. You need to set the call->udata.len field to 0. Serial endpoints ignore the call->udata.buf field.

OTRcvDisconnect

The OTRcvDisconnect function returns information about why a connection attempt failed or an established connection was terminated.

Because serial endpoints do not allow application-specific data to be associated with a disconnect, you need to set the discon->udata.len field to 0. Serial endpoints ignore the discon->udata.buf field.